Background

The Import flow on /projects previously reused the New Project path and only created an empty project. It did not perform a real repository import.
This PR implements the minimum viable end-to-end loop: create project metadata first, then asynchronously import repository code into the sandbox.

Scope

In scope

• Real GitHub import using GitHub App installation tokens (git clone)
• Project-level import lifecycle states and error visibility
• Non-blocking API behavior (importProjectFromGitHub returns immediately)
• Event-first execution path with polling reconcile as fallback
• Import dialog integration with status polling and user feedback

Out of scope

• Automatic skills injection
• Automatic Claude/Code CLI startup
• One-click retry button after import failure

Design

Import state machine

• PENDING: waiting for sandbox readiness
• CLONING: import in progress
• READY: import completed
• FAILED: import failed (project remains usable)

Failure policy matches New Project: do not delete/rollback project on import failure.

Implementation

Data model (prisma/schema.prisma)

• Added enum ProjectImportStatus: PENDING | CLONING | READY | FAILED
• Added Project fields:
  • importStatus
  • importError
  • importLockedUntil
  • githubRepoDefaultBranch

Server actions

• lib/actions/project.ts
  • Extracted shared helper createProjectWithSandbox(...) for both new/import paths
  • Added importProjectFromGitHub(payload):
    • auth and installation ownership validation
    • repository validation
    • project creation with GitHub linkage fields and importStatus=PENDING
• lib/actions/github.ts
  • Added default_branch in repository metadata returned to UI

Background execution

• Added lib/jobs/project-import/projectImportReconcile.ts
  • Processes projects in PENDING/CLONING
  • Runs clone when sandbox is RUNNING
  • Updates state to READY on success, FAILED with importError on failure
  • Includes retry behavior and configurable command timeout
• Added lib/repo/project-import.ts
  • Import-specific lock acquisition and state persistence (aligned with existing optimistic locking style)
• lib/startup/index.ts
  • Registers and starts/stops the project-import reconcile job

Event-first + polling fallback

• lib/events/sandbox/sandboxListener.ts
  • Triggers import execution immediately when sandbox transitions to RUNNING
• Reconcile polling remains as a resilience fallback if event-driven execution is missed

Import command behavior

• Uses GitHub App installation token; disables interactive git credential prompts
• Imports into import/<repo>-<projectId>/ (does not overwrite workspace root)
• Hardened ttyd command dispatch to reduce first-attempt stalls/timeouts

Frontend behavior

• app/(dashboard)/projects/_components/import-github-dialog.tsx
  • Calls importProjectFromGitHub instead of createProject
  • Polls /api/projects/:id for importStatus
  • READY: success toast + dialog close + list refresh
  • FAILED: fallback toast (“empty project created; import failed”) + close + refresh

Validation

• Local checks:
  • pnpm lint ✅
  • pnpm build ✅
• Manual validation:
  • Multiple import runs completed successfully
  • No more reproducible long delay pattern before repository appears

Compatibility and risk

• New Project behavior remains unchanged in core flow
• Existing GitHub initialize/push page behavior is preserved
• Main residual risk is external dependency instability (GitHub/ttyd/K8s), mitigated with explicit import states and persisted error details